feat: add configurable CORS support for direct browser clients - #36

Addressed Issues:

Fixes #32

What this changes

The relay served no CORS headers, and http.ServeMux registers no OPTIONS route, so a browser calling it cross-origin failed its preflight with a 404 and no Access-Control-Allow-Origin. The only workaround was a same-origin reverse proxy — fine for consumers willing to run one, but ThruBox ships as a general-purpose relay and consumers without a proxy had no way in.

Adds internal/middleware/cors.go, driven by a new security.allowed_origins list (RELAY_SECURITY_ALLOWED_ORIGINS, comma-separated).

It is off by default. With no origins configured the middleware is a passthrough — no headers, OPTIONS still falls through to the router. Existing deployments see no behaviour change whatsoever.

The one design decision worth reviewing

CORS sits outermost, ahead of APIKeyAuth:

CORS → API Key → Rate Limiter → Router

This is load-bearing, not stylistic. Browsers never attach custom headers to a preflight, so an OPTIONS request carries no X-API-Key. Nested inside APIKeyAuth, every preflight would 401 and the real request would never be sent — CORS would appear configured and still be broken.

The obvious worry is whether this turns CORS into an auth bypass. It does not: only preflights short-circuit. Actual requests fall through to APIKeyAuth and the rate limiter untouched. There is a dedicated test for each half of that (TestCORS_PreflightSurvivesAPIKeyAuth, TestCORS_ActualRequestStillNeedsTheAPIKey).

Other security-relevant choices:

• The concrete origin is echoed, never *. Vary: Origin is set whenever CORS is active — including on rejection — so a shared cache can never serve one origin's response to another.
• Access-Control-Allow-Credentials is never sent. The relay authenticates with a header, not cookies, and advertising credentials alongside * would be a footgun.
• Exact origin matching after trim/lowercase/trailing-slash-strip. Suffix lookalikes (https://app.example.com.evil.tld) and subdomains do not match a parent entry.
• Malformed config fails at startup, not silently at request time. A scheme-less entry, an entry with a path, or "*" mixed with specific origins is rejected by Validate().
• A preflight from an unlisted origin gets 403, so a developer sees why instead of a confusing 404. Non-preflight requests from unlisted origins are still served but carry no ACAO, so the browser hides the response — standard behaviour.

Screenshots/Recordings:

Not applicable — server-side change. Verified against a running binary with RELAY_SECURITY_ALLOWED_ORIGINS=https://app.example.com and RELAY_SECURITY_API_KEY=secret123:

### 1. Preflight from the ALLOWED origin (no API key, as a browser sends it)
HTTP/1.1 204 No Content
Access-Control-Allow-Headers: Content-Type, X-API-Key
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Max-Age: 600
Vary: Origin

### 2. Preflight from a DISALLOWED origin
HTTP/1.1 403 Forbidden
Vary: Origin

### 3. Real POST, allowed origin + API key
HTTP/1.1 201 Created
Access-Control-Allow-Origin: https://app.example.com

### 4. Real POST, allowed origin, NO API key  (CORS must not bypass auth)
HTTP/1.1 401 Unauthorized
Access-Control-Allow-Origin: https://app.example.com

### 5. Cross-origin GET, allowed origin
HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://app.example.com

### 6. Same GET from a DISALLOWED origin -> served, no ACAO, browser hides it
HTTP/1.1 200 OK
Vary: Origin

### 7. Non-browser caller (no Origin header) -> completely untouched
HTTP/1.1 200 OK
(no Access-Control or Vary headers)

Proposed fix items from the issue:

• Handle preflight OPTIONS explicitly
• Access-Control-Allow-Origin, -Allow-Methods (GET, POST, DELETE), -Allow-Headers (Content-Type, plus X-API-Key when configured)
• Configurable origins via security.allowed_origins + RELAY_SECURITY_ALLOWED_ORIGINS, following the existing pattern in internal/config/config.go — not hardcoded *
• README documents the config and both approaches (proxy, or direct with an allowlist)

Additional Notes:

Adds internal/middleware/cors_test.go (18 cases incl. the origin-normalization and suffix-attack table) and internal/config/security_test.go (env parsing and Validate rejection cases).

$ go test ./...
ok  	github.com/AOSSIE-Org/ThruBox-Server/internal/config
ok  	github.com/AOSSIE-Org/ThruBox-Server/internal/middleware

gofmt and go vet are clean on every file this PR touches.

Preflights short-circuit ahead of the rate limiter, so they do not consume a caller's budget. That is deliberate and matches common CORS implementations — answering an OPTIONS is cheap — but flagging it since it is a policy choice, not an accident.

Reviewing alongside #26 and #27: all three were checked against each other before opening. Every pairwise and three-way merge is clean, and the merged tree builds and passes tests in all orders tested. No merge order is required.

Out of scope, spotted while working here (each wants its own issue):

• internal/middleware/ratelimit.go is not gofmt-clean on main — the visitor struct fields are misaligned. Untouched here despite sitting next to the new file.
• .gitignore:34 has a bare relay entry that matches the cmd/relay/ directory, so any new file in that package is silently ignored by git add.
• dangerfile.js requires a checklist item "My PR addresses a single issue" that is absent from .github/PULL_REQUEST_TEMPLATE.md. Added manually below.

Checklist

• My PR addresses a single issue
• My code follows the project's code style and conventions
• I have made corresponding changes to the documentation
• My changes generate no new warnings or errors
• I have joined the Discord server and I will share a link to this PR with the project maintainers there
• I have read the Contributing Guidelines

⚠️ AI Notice

This PR was drafted with Claude Code, model Claude Opus 5.

• Scope of AI assistance: implementation, tests, README and config.yaml documentation, and this description.
• Verification: every scenario above was executed with curl against a running binary, not asserted from reading the code. The middleware-ordering behaviour and the "CORS is not an auth bypass" property each have a dedicated unit test as well as a live check. go build, go vet, gofmt and go test were run and are reported above.
• This touches a security control (an origin allowlist). Please review the ordering decision and the matching rules on their merits rather than trusting the test names.
• Opened as a draft for maintainer review.

Summary by CodeRabbit

• New Features

  • Added configurable CORS support for browser-based requests.
  • Supports wildcard or specific allowed origins through configuration or environment variables.
  • Valid preflight requests now receive appropriate CORS headers and a successful response.
  • Startup logs indicate configured CORS origins when enabled.

• Documentation

  • Added setup guidance, examples, origin validation rules, proxy usage, and security considerations for CORS.